Apple Developer Connection 1998 Fall: Game Toolkit

home *** CD-ROM | disk | FTP | other *** search

/ Apple Developer Connection 1998 Fall: Game Toolkit / Disc.iso / SDKs / Mac OS USB DDK_v1.0.1 / Mac OS USB DDK Readme < prev next >

Wrap

Text File | 1998-09-03 | 19.3 KB | 516 lines | [ttro/ttxt]

*** *** Universal Serial Bus(tm) (USB) for the Mac OS *** Mac OS USB 1.0.1 DDK Developer Release Notes *** Copyright 1998 Apple Computer, Inc. *** Table of Contents: ------------------------------------------------------------- Changes from USB v1.0 -> v1.0.1 USB Fundamentals Getting started with Mac OS USB Installing the Mac OS USB Software Using the Mac OS USB DDK under MPW Installing the Mac OS USB DDK into MPW for the First Time Updating a Previously Installed USB DDK for MPW Using the Mac OS USB DDK with MetroWerks CodeWarrior Installing the Mac OS USB DDK for CodeWarrior for the First Time Updating a Previously Installed Mac OS USB DDK for CodeWarrior Using the CodeWarrior Project Files Installing the Mac OS USB Components onto your Target System Description of Installed Files Known Problems Contact Information ------------------------------------------------------------- Changes from USB v1.0 -> v1.0.1 ------------------------------- Refer to the document "Mac OS USB v1.0.1 Readme" for a description of the changes between the v1.0 and v1.0.1 DDK. USB Fundamentals ---------------- For the coming generation of Power Macintosh systems, USB is the primary interface for connections to low to medium speed peripheral devices. There a numerous advantages for adopting the USB standard on Macintosh, and they are discussed in the "Mac OS USB DDK API Reference Guide". On the future Macintosh systems there will be no ADB, Serial Port, or SCSI connections. USB will be the primary port for connecting peripheral devices to the Macintosh. The DDK provides the tools, interfaces, system files, and module examples for you to start development of USB products for the Macintosh. The DDK provides the same release of USB component software that ships on the introductory release of the Power Macintosh iMac system. Getting started with Mac OS USB ----------------------------- As of the writing of this note, Power Macintosh Systems which have USB support built-in, are under development. Seed units for Developers are limited and Apple will be unable to provide developments systems to all developers. To jump-start the development process for Mac OS USB, you can obtain a PCI USB card from three sources - ADS, OPTi and CMD Technology. As other sources for PCI USB cards become available, we will revise this readme to include them. For OPTi, the web page is <http://www.opti.com/html/usbsolutions.html>. For ADS, the web page is <http://www.adstechnologies.com/> For CMD Technology, Inc, the web page is <http://www.cmd.com/>. We advise you to obtain cards from all sources so that you can test on all cards to ensure maximum compatibility. With these cards, and the supplied software, you can start work on developing your USB Modules to support your devices, along with the associated applications. The DDK provides examples for both the MPW and MetroWerks CodeWarrior Pro environments. Please carefully, read the notes below, on how you will need to configure your environment to build the example modules. Installing the Mac OS USB Software --------------------------------- To install the USB System Software components, drag copy the contents of the folder :USBDDK:Extensions-AppleBuilt: to the Extensions folder, and reboot. Important Notes on Installation and Use of this DDK software ------------------------------------------------------------ This DDK will let you look at the sources to some working class drivers, build the examples, and develop & build your own code. Please remember that these driver samples are Copyright Apple Computer, Inc.. You may use the supplied code to develop Class Drivers for your devices. As for publishing the source code, please check first with the Mac OS USB DDK License agreement, included in this DDK. The current driver samples may, reflect the latest state of the art of driver writing for USB in the Mac OS. Note that the PrinterClassModule sample is for example purpose only. This sample is the basis for real drivers under development, however we are unable to provide the actual class driver code. The remaining examples are the real code for the Keyboard HID, Mouse HID, Universal HID, and Composite class drivers which will ship on the iMac While not extensively tested (by the development team), the sample sources have been tweaked slightly to make builds under CodeWarrior some what less problematic. The project files are provided to help jumpstart your development process. Using the Mac OS USB DDK under MPW --------------------------------- The following are guidelines for using this DDK with the MPW programming environment. 1. You must have MPW 3.4.2 (or later) from ETO 23. We are not supporting the use of any versions of MPW previous to v3.4.2. 2. You must use the Universal Interfaces&Libraries 3.1 from the Apple ftp site. Follow the instructions which are provided with the Interfaces&Libraries download to upgrade the MPW programming environment. The URL for the Developer Development Kits web page is <http://developer.apple.com/sdk/> 3. You should update the USB.h file in the Universal Interfaces CIncludes folder with the USB.h file from the USBDDK Folder. 4. Within MPW, there will be the USBDDK menu. Choose the desired sample module to build from the "Select Example" menu item. Use the "Build Driver or Example" menu item to build the example file. The driver modules which you build will be placed into the "USBDDK:Extensions-DDKBuilt:" folder. Installing the Mac OS USB DDK into MPW for the First Time -------------------------------------------------------- 1. Drop the UserStartup•USBDDK into your MPW folder. 2. Ensure that the name of the development system's USB DDK folder is USBDDK. The MPW scripts supplied in this DDK will fail if the folder is named differently. It has been reported that the USBDDK MPW startup script doesn't handle spaces that are part of the complete pathname correctly. This should be corrected in a later release. 3. Launch MPW You'll be prompted to point to *YOUR* DDK folder. That is, the USBDDK folder on your hard drive, not a projector database on a server. 4. Drag the "Extensions-AppleBuilt" items into your "target" system's system folder, not the development system's system folder! The development system only needs the contents of the DDK and MPW folders. Updating a Previously Installed USB DDK for MPW --------------------------------------------------- 0. Note the change of name for the DDK from NeptuneDDK to USBDDK. 1. Delete the file UserStartup•NeptuneDDK from your MPW folder. If this file is left in, MPW will alert you to the fact that it was unable to complete execution of a startup command. 2. Drop the UserStartup•USBDDK into your MPW folder. This file may have changed from the last release of the DDK 3. Drag *your* folders from inside the "Drivers" folder from the old DDK to the Driver folder of the new USB DDK folder. Make sure that the name of the folder is changed to USBDDK 4. Change the name of the *new* USB DDK folder to match *exactly* what your old USBDDK folder was called. 5. If you don't get the name exactly right, then MPW will ask you to locate the folder the next time you start it. Be warned: Spaces in the DDK folder name are NOT recommended. 6. Start MPW. Any drivers you've moved from the old DDK to the new DDK's "Drivers" folder will automatically appear in the USBDDK Drivers submenu. Using the Mac OS USB DDK with MetroWerks CodeWarrior --------------------------------------------------- We have supplied MetroWerks CodeWarrior project files for all of the USB Modules code examples. All of the project files were created using CodeWarrior Pro 1, IDE 2.0. The project files are also compatible with CodeWarrior Pro IDE 2.1 and 3.0. For the CodeWarrior IDE environments v2.0 - v3.0, you must use the Universal Interface & Libraries v3.1. The examples will not build using the interfaces supplied with the CodeWarrior v.2 - v3.0 environments. The URL for the Developer Development Kits web page is <http://developer.apple.com/sdk/> As mentioned for MPW, it is highly recommend that you use one Macintosh for coding purposes and one Mac (aka "Target" system) for checkout/testing purposes. The supplied project files will place the built drivers and extensions into the Target folder of the DDK. Installing the Mac OS USB DDK for CodeWArrior for the First Time ----------------------------------------------------------- 1. You can place the USBDDK anywhere on your development system for the CodeWarrior environment. The access paths for the project files are project and compiler relative. If you move the examples folders out of the DDK, you must fix the access paths so that the sources can be found. 2. Ensure that the CodeWarrior IDE environment has the Universal Interfaces and Libraries 3.1 installed. The download file from the DDK website includes instructions for upgrading your CodeWarrior environment. Note that if you upgrade your interfaces, you will also need to upgrade your precompiled headers. The supplied CodeWarrior project files do not use precompiled headers. 3. Copy the USB.h file included in this SDK to the ":Mac OS Support:Headers:Universal Headers:" folder. 4. You will need to create a folder by the name "USBDDK:Extensions-MCWBuilt" This is the folder where the CodeWarrior projects will place the built examples. If this folder does not exist, or the folder name is named differently, the class driver samples will be created in the CodeWarrior folder. Updating a Previously Installed Mac OS USB DDK for CodeWarrior ------------------------------------------------------------- 0. Note the change of name for the DDK from NeptuneDDK to USBDDK. 1. Copy the USB.h file included in this SDK to the ":Mac OS Support:Headers:Universal Headers:" folder. Do not use the USB.h header file from an earlier USB DDK with the supplied project files, as the examples may not build. 2. If you experience compiler errors with the program samples, check whether you have updated the USB.h header in the ":Mac OS Support:Headers:Universal Headers:" folder. 3. You will need to create a folder by the name "USBDDK:Extensions-MCWBuilt" This is the folder where the CodeWarrior projects will place the built examples. If this folder does not exist, or the folder name is named differently, the class driver samples will be created in the CodeWarrior folder. Using the CodeWarrior Project Files --------------------------------- For the following samples, there is only a single target for each project: CompositeClassDriver KeyboardModule MouseModule UniversalModule For the PrinterClassDriver example, compile the targets in the following order 1. PrinterClassDRVR - creates the 68K DRVR resource 2. PrintClassDriver - creates the USB PrintClassDriver module 3. ChooserPack.rsrc - creates the "PACK" resource 4. USB Chooser Driver - creates the Chooser extension for the USB printer Installing the Mac OS USB Components onto your Target System ----------------------------------------------------------- IMPORTANT NOTE: Do not install the USB Extensions and Libraries into the System Folder of a CPU that has the USB Support integrated into the System ROM. 1. Delete any existing files prefixed with "USB" from your system folder's extension folder. This applies only if an earlier pre-release version of Mac OS USB DDK software had been installed. 2. Drag all the files from the 'USBDDK:Extensions-AppleBuilt' folder to the System Folder (ultimately destined for the system folder's extension folder). 3. Verify that all of the files that you dragged from the 'Extensions-AppleBuilt' folder were placed in the system folder's extensions folder. Description of Installed Files -------------------------- Files in the 'Extensions-AppleBuilt' folder: Files: Description: USBCompositeDriver A class driver which is loaded for class 0 & and subclass 0 devices (typically keyboards & mice, although a few printers & modems appear as composite class devices). USBFamilyExpert The INIT (actually an 'expt') portion of the Family Expert. Loaded prior to the INIT parade, it starts the 'find a USB bus (i.e. UIM driver), loads the hub driver (for the root hub), and starts the hub driver running. Once running, the hub driver locates devices attached to the port and asks the FamilyExpertLib to load drivers for the devices connected to the hub's ports. USBHubDriver0 & The Hub driver for the root hub, the Apple USB USBHubDriver1 keyboard's hub, and some 3rd party hubs. USBKeyboardModule The HID Module loaded for a keyboard interface (typically in a compound device) USBMouseModule A HID Module loaded for a mouse interface (typically in a compound device). USBHIDUniversalModule A HID Module designed to support a number of 3rd party gaming devices via Game Sprockets. Refer to the "Mac OS USB Compatibility Notes" for a description of the game devices supported. USBOpenHCIDriver The HAL (Hardware Abstraction Layer), also known as the "UIM" (USB Interface Module). This driver provides an abstracted interface to the OpenHCI host controllers on Mac motherboards and PCI controller cards. USBPrintDriver A Printing Class Driver for experimentation purposes. Printing WILL NOT be functional simply with the addition of this file. The chooser extension needed for USB printing is still in development and has not yet been released. Known Issues ------------ The following is a list of known issues with this final release of the USB DDK. - The Mac OS USB DDK API Reference is close to final. This DDK includes draft v15. When the document is final, a copy will be placed on the Mac OS USB Developer web page at <http://developer.apple.com/dev/usb/>. - The Mac OS USB DDK v1.0 does not provide any isochronous support. Isochronous support will be implemented in a future release of the Mac OS USB DDK. - For the USBBulkRead call, the buffer which you pass via the usbBuffer field, must be aligned to a "MaxPacketSize" boundary. A code snippet is provided in the USB Reference Guide to demonstrate how to align a read buffer to a "MaxPacketSize" boundary. Note that the buffer can be of any size, but preferably larger than "MaxPacketSize". - In the PrinterClassDriver sample, you may encounter a compiler error while compiling the ChooserPack.rsrc target under CodeWarrior. The "declaration syntax error" is reported in the "Chooser.h" file regarding the use of the CFragConnectionID symbol. To fix this problem, add the statement #include <CodeFragments.h> to the list of included header files at the top of the header listing. - The USBGetPipeStatusByReference call does not function correctly. The pipe state is not returned in the state parameter. Instead one of these errors is returned: noErr specified pipe is active kUSBPipeIdleError specified pipe is in the idle state kUSBPipeStalledError specified pipe is stalled In a future release of USB, the USBGetPipeStatusByReference call will correctly return the pipe state in the state parameter. Note that the kUSBUnknownPipeErr is a valid response for which the pipe state is not returned. - The USBSetPipeIdleByReference call does not function correctly. The following errors are returned, even though the call succeeded. kUSBIdleStalled pipe was stalled, pipe is still idled despite error kUSBPipeIdleError pipe was already idle - The USBSetPipeActiveByReference call does not function correctly. The following error is returned, even though the call succeeded. kUSBPipeIdleError pipe was previously idle, pipe is still made active - The USBResetPipeByReference call does not function correctly. If kUSBPipeIdleError error is returned, the pipe may or may not have been made active, depending on whether the pipe was previously stalled or not. An idle pipe which was not stalled is not affected. An idle pipe which was also stalled is made active. This kUSBPipeStalledError error is also returned if the pipe was previously idle. The call has succeeded despite the error. - In the v1.0 release of the USB Services software, config services will fail for a device whose configuration descriptors consist solely of a configuration descriptor and an interface descriptor (total length 18 bytes). Any call which tries to access the configuration descriptor, will return a kUSBNotFound Error. This problem is fixed in later versions. It is possible to work around this problem in 1.0 by changing the firmware of the device if possible. Adding any extra descriptor to the configuration descriptors will solve the problem. This addition can be as simple as a 2 byte dummy descriptor of the form: Descriptor length: 2 Descriptor type: Anything (0xFF seems to be suitable). Contact Information ------------------- Mac OS USB DDK Upgrades and latest information: Check the Developer Development Kits web page for upgrades to the Mac OS USB DDK. The web page is <http://developer.apple.com/sdk/> For the latest information on Mac OS USB, check the Mac OS USB web page. The web page is <http://usb.apple.com> For Bug Reports: To ensure the appropriate data is collected, please use the Bug Reporter to send us your bug reports. The Bug Reporter can be found at: <http://developer.apple.com/bugreporter> When reporting problems, please include the machine configuration, including the vendor of the PCI USB card which you have tested with. For Technical Questions: Contact Worldwide Developer with purchased development-level technical support incidents at dts@apple.com Technical support incidents are bundled in our Premier and Select Developer programs. For information about joining our programs, please visit our Apple Developer Connection web site at http://developer.apple.com/programs. If you have never purchased a technical support incident and would like to find out how to do so, please visit the following site: http://developer.apple.com/programs/techsupport.html . Comments, Suggestions and Enhancement Requests Please send all comments and suggestions regarding the Mac OS USB DDK to usb@apple.com All email sent to this address will be read, however, we will not be to respond to all of your comments and suggestions.